OpenClaw 定时任务完全指南

定时任务让 AI 助理能够主动执行周期性任务，如每日报告、定期检查、定时提醒等。本文详细介绍如何使用 cron 工具配置和管理定时任务。

一、定时任务应用场景

典型用例

每日报告：早晨发送新闻摘要、天气预报
定期检查：监控系统状态、网站可用性
定时提醒：会议提醒、生日提醒、任务截止提醒
数据同步：定期备份、数据更新
自动化运维：日志清理、缓存刷新

二、核心概念

1. cron 工具结构

javascript

cron(
  action="add",
  job={
    name: "每日早晨报告",
    schedule: {
      kind: "cron",
      expr: "0 8 * * *",  // 每天 8:00
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",   // 或 "systemEvent"
      message: "生成每日报告",
      timeoutSeconds: 300
    },
    sessionTarget: "isolated",  // 或 "main"
    enabled: true
  },
  delivery: {
    mode: "announce"  // 或 "webhook"
  }
)

2. 调度类型

Cron 表达式（周期性）

javascript

// 每天 8:00
{ kind: "cron", expr: "0 8 * * *", tz: "Asia/Shanghai" }

// 每周一 9:00
{ kind: "cron", expr: "0 9 * * 1", tz: "Asia/Shanghai" }

// 每小时整点
{ kind: "cron", expr: "0 * * * *" }

// 每 15 分钟
{ kind: "cron", expr: "*/15 * * * *" }

间隔执行（相对时间）

javascript

// 每 30 分钟执行一次
{ kind: "every", everyMs: 1800000 }

// 每 24 小时执行一次，从指定时间开始
{ 
  kind: "every", 
  everyMs: 86400000,
  anchorMs: new Date("2026-03-19T08:00:00+08:00").getTime()
}

一次性执行（绝对时间）

javascript

// 在指定时间执行一次
{ kind: "at", at: "2026-03-20T08:00:00+08:00" }

3. 负载类型

agentTurn（AI 执行任务）

javascript

payload: {
  kind: "agentTurn",
  message: "检查邮箱并总结未读邮件",
  model: "qwen-max",      // 可选：指定模型
  thinking: "on",         // 可选：启用深度思考
  timeoutSeconds: 600     // 超时时间
}

特点：

在隔离会话中运行
可以调用所有工具
支持流式输出
适合复杂任务

systemEvent（系统事件）

javascript

payload: {
  kind: "systemEvent",
  text: "执行 /home/pao/scripts/backup.sh 备份脚本"
}

特点：

在主会话中执行
作为系统消息处理
适合简单触发
注意： sessionTarget: "main" 必须使用 systemEvent

三、实战案例 1：每日早晨报告

需求

每天早晨 8:00 自动执行：

检查未读邮件
查看今日日历
获取天气预报
生成汇总报告发送到飞书

完整配置

javascript

cron(
  action="add",
  job={
    name: "每日早晨报告",
    schedule: {
      kind: "cron",
      expr: "0 8 * * *",
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: `
请生成每日早晨报告，包括：

1. 检查未读邮件（如有紧急邮件请标注）
2. 查看今日日历事件（特别是 2 小时内的）
3. 获取驻马店天气预报
4. 检查是否有待处理的提醒

生成简洁的报告，使用以下格式：

📧 邮件：[数量] 封未读，[紧急内容摘要]
📅 今日日程：[事件列表]
🌤️ 天气：[温度、天气状况、建议]
⏰ 提醒：[待办事项]

如果没有重要内容，回复"一切正常"即可。
      `,
      timeoutSeconds: 300
    },
    sessionTarget: "isolated",
    delivery: {
      mode: "announce"
    }
  }
)

执行结果示例

📊 每日早晨报告 - 2026 年 3 月 19 日

📧 邮件：3 封未读
   - [紧急] 项目评审会议改期通知（今天 10:00）
   - 系统自动备份完成报告
   - 订阅周刊：AI 技术前沿第 52 期

📅 今日日程：
   - 10:00 项目评审会议（已改期）
   - 14:00 团队周会
   - 16:30 客户演示

🌤️ 天气：驻马店 晴 12-23°C
   建议：天气晴朗，适合户外活动

⏰ 提醒：
   - 明天是母亲生日，记得准备礼物
   - 周五前提交季度报告

四、实战案例 2：系统健康检查

需求

每 4 小时检查一次系统状态，异常时立即通知。

完整配置

javascript

cron(
  action="add",
  job={
    name: "系统健康检查",
    schedule: {
      kind: "cron",
      expr: "0 */4 * * *",  // 每 4 小时
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: `
执行系统健康检查：

1. 检查 OpenClaw 网关状态
   - 运行：openclaw gateway status
   
2. 检查 Nginx 服务
   - 运行：systemctl status nginx
   
3. 检查磁盘空间
   - 运行：df -h /home
   
4. 检查内存使用
   - 运行：free -h

5. 检查关键进程
   - 运行：ps aux | grep -E "node|nginx"

检查标准：
- 磁盘使用 > 90%：严重
- 内存使用 > 90%：严重  
- 服务未运行：严重

发现严重问题时：
1. 尝试自动修复（如重启服务）
2. 发送通知到飞书
3. 记录详细日志

无问题时回复"系统正常"，不需要发送通知。
      `,
      timeoutSeconds: 600
    },
    sessionTarget: "isolated"
  }
)

告警消息示例

🚨 系统告警 - 2026-03-19 12:00

【严重】磁盘空间不足
- 使用率：92%
- 位置：/home
- 可用：8.5GB

【已执行操作】
1. 清理浏览器缓存：释放 2.1GB
2. 清理日志文件：释放 1.5GB
3. 当前使用率：87%

【建议】
- 考虑清理旧的项目文件
- 检查是否有大文件可删除

五、实战案例 3：网站内容监控

需求

每小时检查竞争对手网站，发现新内容时通知。

完整配置

javascript

cron(
  action="add",
  job={
    name: "竞争对手网站监控",
    schedule: {
      kind: "cron",
      expr: "0 * * * *",  // 每小时
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: `
监控竞争对手网站更新：

1. 抓取目标页面
   - https://competitor.com/blog
   - https://competitor.com/products

2. 提取最新内容
   - 文章标题
   - 发布时间
   - 摘要内容

3. 与上次检查结果对比
   - 读取 ~/.openclaw/workspace/competitor-last-check.json
   - 比较是否有新内容

4. 如有新内容：
   - 发送通知到飞书
   - 更新检查记录文件
   - 总结新内容要点

5. 如无新内容：
   - 静默退出（不发送通知）
      `,
      timeoutSeconds: 300
    },
    sessionTarget: "isolated"
  }
)

六、Webhook 集成

场景

定时任务完成后，将结果发送到外部系统（如钉钉、企业微信）。

配置示例

javascript

cron(
  action="add",
  job={
    name: "每日数据同步",
    schedule: {
      kind: "cron",
      expr: "0 2 * * *",  // 每天凌晨 2 点
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "执行数据同步任务，完成后返回 JSON 结果",
      timeoutSeconds: 1800
    },
    sessionTarget: "isolated",
    delivery: {
      mode: "webhook",
      to: "https://api.example.com/webhook/sync-result",
      bestEffort: true  // 发送失败不重试
    }
  }
)

Webhook payload 示例

json

{
  "jobId": "xxx-xxx-xxx",
  "jobName": "每日数据同步",
  "status": "finished",
  "startedAt": 1710813600000,
  "finishedAt": 1710814500000,
  "durationMs": 900000,
  "result": {
    "syncedRecords": 1250,
    "errors": 0,
    "summary": "同步完成，无错误"
  }
}

七、任务管理

查看任务列表

javascript

// 查看所有任务（包括禁用的）
cron(action="list", includeDisabled=true)

更新任务

javascript

// 修改任务执行时间
cron(
  action="update",
  jobId="task-id-xxx",
  patch={
    schedule: {
      kind: "cron",
      expr: "0 9 * * *"  // 改为每天 9:00
    }
  }
)

// 禁用任务
cron(
  action="update",
  jobId="task-id-xxx",
  patch={ enabled: false }
)

删除任务

javascript

cron(action="remove", jobId="task-id-xxx")

手动触发

javascript

// 立即执行一次
cron(action="run", jobId="task-id-xxx", runMode="force")

查看执行历史

javascript

cron(action="runs", jobId="task-id-xxx")

八、最佳实践

1. 任务命名规范

javascript

// 好的命名
name: "每日早晨报告 - 邮件 + 日历 + 天气"
name: "系统健康检查 - 每 4 小时"
name: "网站备份 - 每天凌晨 3 点"

// 避免模糊命名
name: "定时任务 1"  // ❌
name: "检查"       // ❌

2. 错误处理

javascript

payload: {
  kind: "agentTurn",
  message: `
执行任务，注意：
1. 任何错误都要记录详细日志
2. 严重错误发送通知
3. 可恢复的错误尝试重试（最多 3 次）
4. 无论成功失败都要更新状态文件
  `,
  timeoutSeconds: 600
}

3. 避免任务堆积

javascript

// 设置合理的超时
timeoutSeconds: 300  // 5 分钟超时

// 检查是否有未完成的任务
const runs = cron(action="runs", jobId="xxx")
if (runs.some(r => r.status === "running")) {
  // 跳过本次执行或终止卡住的任务
}

4. 日志记录

javascript

// 在任务中记录详细日志
message: `
执行数据备份：
1. 记录开始时间和初始状态
2. 每一步都记录进度
3. 记录最终结果和耗时
4. 异常情况记录堆栈信息

日志保存到：/var/log/backup-YYYY-MM-DD.log
`

九、常见问题

Q: 时区如何设置？

A: 使用 tz 字段指定时区，如 "Asia/Shanghai"。不指定则使用 UTC。

Q: 任务执行失败怎么办？

查看执行历史：cron(action="runs", jobId="xxx")
检查错误日志
调整超时时间或重试逻辑

Q: 如何调试定时任务？

A: 使用 cron(action="run", jobId="xxx", runMode="force") 手动触发测试。

Q: 任务可以互相触发吗？

A: 可以，在任务中调用 cron(action="run", jobId="yyy") 触发其他任务。

十、总结

定时任务是实现 AI 助理主动性的关键：

场景	推荐配置
每日报告	cron, 每天固定时间
定期检查	cron, 每 N 小时
定时提醒	at, 一次性执行
间隔任务	every, 相对间隔

合理使用定时任务，让你的 AI 助理从"被动响应"变为"主动服务"。

相关资源：

OpenClaw 定时任务完全指南 ​

一、定时任务应用场景 ​

典型用例 ​

二、核心概念 ​

1. cron 工具结构 ​

2. 调度类型 ​

Cron 表达式（周期性） ​

间隔执行（相对时间） ​

一次性执行（绝对时间） ​

3. 负载类型 ​

agentTurn（AI 执行任务） ​

systemEvent（系统事件） ​

三、实战案例 1：每日早晨报告 ​

需求 ​

完整配置 ​

执行结果示例 ​

四、实战案例 2：系统健康检查 ​

需求 ​

完整配置 ​

告警消息示例 ​

五、实战案例 3：网站内容监控 ​

需求 ​

完整配置 ​

六、Webhook 集成 ​

场景 ​

配置示例 ​

Webhook payload 示例 ​

七、任务管理 ​

查看任务列表 ​

更新任务 ​

删除任务 ​

手动触发 ​

查看执行历史 ​

八、最佳实践 ​

1. 任务命名规范 ​

2. 错误处理 ​

3. 避免任务堆积 ​

4. 日志记录 ​

九、常见问题 ​

Q: 时区如何设置？ ​

Q: 任务执行失败怎么办？ ​

Q: 如何调试定时任务？ ​

Q: 任务可以互相触发吗？ ​

十、总结 ​

OpenClaw 定时任务完全指南

一、定时任务应用场景

典型用例

二、核心概念

1. cron 工具结构

2. 调度类型

Cron 表达式（周期性）

间隔执行（相对时间）

一次性执行（绝对时间）

3. 负载类型

agentTurn（AI 执行任务）

systemEvent（系统事件）

三、实战案例 1：每日早晨报告

需求

完整配置

执行结果示例

四、实战案例 2：系统健康检查

需求

完整配置

告警消息示例

五、实战案例 3：网站内容监控

需求

完整配置

六、Webhook 集成

场景

配置示例

Webhook payload 示例

七、任务管理

查看任务列表

更新任务

删除任务

手动触发

查看执行历史

八、最佳实践

1. 任务命名规范

2. 错误处理

3. 避免任务堆积

4. 日志记录

九、常见问题

Q: 时区如何设置？

Q: 任务执行失败怎么办？

Q: 如何调试定时任务？

Q: 任务可以互相触发吗？

十、总结